Overview | Package | Class | Use | Tree | Index | Help
| Java Debug Interface
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.sun.jdi
Interface ObjectReference

All Superinterfaces:
  Mirror, Value

All Known Subinterfaces:
  ArrayReference, ClassLoaderReference, ClassObjectReference, StringReference, ThreadGroupReference, ThreadReference

public interface ObjectReference
extends Value

An object that currently exists in the target VM. An ObjectReference mirrors only the object itself and is not specific to any `Field` or `LocalVariable` to which it is currently assigned. An ObjectReference can have 0 or more references from field(s) and/or variable(s).

Any method on `ObjectReference` which directly or indirectly takes `ObjectReference` as an parameter may throw `VMDisconnectedException` if the target VM is disconnected and the `VMDisconnectEvent` has been or is available to be read from the `EventQueue`.

Any method on `ObjectReference` which directly or indirectly takes `ObjectReference` as an parameter may throw `VMOutOfMemoryException` if the target VM has run out of memory.

Any method on `ObjectReference` or which directly or indirectly takes `ObjectReference` as parameter may throw `ObjectCollectedException` if the mirrored object has been garbage collected.

Since:
  1.3

Field Summary
`static int` | `INVOKE_NONVIRTUAL` Perform non-virtual method invocation
`static int` | `INVOKE_SINGLE_THREADED` Perform method invocation with only the invoking thread resumed

Method Summary
`void` | `disableCollection()` Prevents garbage collection for this object.
`void` | `enableCollection()` Permits garbage collection for this object.
`int` | `entryCount()` Returns the number times this object's monitor has been entered by the current owning thread.
`boolean` | `equals(Object obj)` Compares the specified Object with this ObjectReference for equality.
`Value` | `getValue(Field sig)` Gets the value of a given instance or static field in this object.
`Map` | `getValues(List fields)` Gets the value of multiple instance and/or static fields in this object.
`int` | `hashCode()` Returns the hash code value for this ObjectReference.
`Value` | `invokeMethod(ThreadReference thread, Method method, List arguments, int options)` Invokes the specified `Method` on this object in the target VM.
`boolean` | `isCollected()` Determines if this object has been garbage collected in the target VM.
`ThreadReference` | `owningThread()` Returns an `ThreadReference` for the thread, if any, which currently owns this object's monitor.
`ReferenceType` | `referenceType()` Gets the `ReferenceType` that mirrors the type of this object.
`void` | `setValue(Field field, Value value)` Sets the value of a given instance or static field in this object.
`long` | `uniqueID()` Returns a unique identifier for this ObjectReference.
`List` | `waitingThreads()` Returns a List containing a `ThreadReference` for each thread currently waiting for this object's monitor.

Methods inherited from interface com.sun.jdi.Value
`type`

Methods inherited from interface com.sun.jdi.Mirror
`toString, virtualMachine`

Field Detail

### INVOKE_SINGLE_THREADED

    public static final int INVOKE_SINGLE_THREADED

  Perform method invocation with only the invoking thread resumed

  See Also:
    Constant Field Values

### INVOKE_NONVIRTUAL

    public static final int INVOKE_NONVIRTUAL

  Perform non-virtual method invocation

  See Also:
    Constant Field Values

Method Detail

### referenceType

    public ReferenceType referenceType()

  Gets the `ReferenceType` that mirrors the type of this object. The type may be a subclass or implementor of the declared type of any field or variable which currently holds it. For example, right after the following statement.

  `Object obj = new String("Hello, world!");`

  The ReferenceType of obj will mirror java.lang.String and not java.lang.Object.

  The type of an object never changes, so this method will always return the same ReferenceType over the lifetime of the mirrored object.

  The returned ReferenceType will be a `ClassType` or `ArrayType` and never an `InterfaceType`.

  Returns:
    the `ReferenceType` for this object.

### getValue

    public Value getValue(Field sig)

  Gets the value of a given instance or static field in this object. The Field must be valid for this ObjectReference; that is, it must be from the mirrored object's class or a superclass of that class.

  Parameters:
    `sig` - the field containing the requested value
  Returns:
    the `Value` of the instance field.
  Throws:
    `IllegalArgumentException` - if the field is not valid for this object's class.

### getValues

    public Map getValues(List fields)

  Gets the value of multiple instance and/or static fields in this object. The Fields must be valid for this ObjectReference; that is, they must be from the mirrored object's class or a superclass of that class.

  Parameters:
    `fields` - a list of `Field` objects containing the requested values.
  Returns:
    a Map of the requested `Field` objects with their `Value`.
  Throws:
    `IllegalArgumentException` - if any field is not valid for this object's class.

### setValue

    public void setValue(Field field,
                         Value value)
                  throws InvalidTypeException,
                         ClassNotLoadedException

  Sets the value of a given instance or static field in this object. The `Field` must be valid for this ObjectReference; that is, there must be a widening reference conversion from this object to the field's type. If static, the field must not be final.

  Object values must be assignment compatible with the field type (This implies that the field type must be loaded through the enclosing class's class loader). Primitive values must be either assignment compatible with the field type or must be convertible to the field type without loss of information. See the JavaTM Language Specification. section 5.2 for more information on assignment compatibility.

  Parameters:
    `field` - the field containing the requested value
    `value` - the new value to assign
  Throws:
    `IllegalArgumentException` - if the field is not valid for this object's class.
    `InvalidTypeException` - if the value's type does not match the field's type.
    `ClassNotLoadedException` - if the field type has not yet been loaded through the appropriate class loader.

### invokeMethod

    public Value invokeMethod(ThreadReference thread,
                              Method method,
                              List arguments,
                              int options)
                       throws InvalidTypeException,
                              ClassNotLoadedException,
                              IncompatibleThreadStateException,
                              InvocationException

  Invokes the specified `Method` on this object in the target VM. The specified method can be defined in this object's class, in a superclass of this object's class, or in an interface implemented by this object. The method may be a static method or an instance method, but not a static initializer or constructor. Use `ClassType.newInstance(com.sun.jdi.ThreadReference, com.sun.jdi.Method, java.util.List, int)` to create a new object and run its constructor.

  The method invocation will occur in the specified thread. Method invocation can occur only if the specified thread has been suspended by an event which occurred in that thread. Method invocation is not supported when the target VM has been suspended through `VirtualMachine.suspend()` or when the specified thread is suspended through `ThreadReference.suspend()`.

  The specified method is invoked with the arguments in the specified argument list. The method invocation is synchronous; this method does not return until the invoked method returns in the target VM. If the invoked method has a return type other than `void`, a mirror of the return value is returned by this method; otherwise, `null` is returned. If the invoked method throws an exception, this method will throw an `InvocationException` which contains a mirror to the exception object thrown.

  Object arguments must be assignment compatible with the argument type (This implies that the argument type must be loaded through the enclosing class's class loader). Primitive arguments must be either assignment compatible with the argument type or must be convertible to the argument type without loss of information. See the Java Language Specification. section 5.2 for more information on assignment compatibility.

  By default, the method is invoked using dynamic lookup as documented in the Java Language Specification second edition, section 15.12.4.4; in particular, overriding based on the runtime type of the object mirrored by this `ObjectReference` will occur. This behavior can be changed by specifying the `INVOKE_NONVIRTUAL` bit flag in the `options` argument. If this flag is set, the specified method is invoked whether or not it is overridden for this object's runtime type. The method, in this case, must not belong to an interface and must not be abstract. This option is useful for performing method invocations like those done with the `super` keyword in the Java programming language.

  By default, all threads in the target VM are resumed while the method is being invoked if they were previously suspended by an event or by `VirtualMachine.suspend()` or `ThreadReference.suspend()`. This is done to prevent the deadlocks that will occur if any of the threads own monitors that will be needed by the invoked method. It is possible that breakpoints or other events might occur during the invocation. Note, however, that this implicit resume acts exactly like `ThreadReference.resume()`, so if the thread's suspend count is greater than 1, it will remain in a suspended state during the invocation. By default, when the invocation completes, all threads in the target VM are suspended, regardless their state before the invocation.

  The resumption of other threads during the invocation can be prevented by specifying the `INVOKE_SINGLE_THREADED` bit flag in the `options` argument; however, there is no protection against or recovery from the deadlocks described above, so this option should be used with great caution. Only the specified thread will be resumed (as described for all threads above). Upon completion of a single threaded invoke, the invoking thread will be suspended once again. Note that any threads started during the single threaded invocation will not be suspended when the invocation completes.

  If the target VM is disconnected during the invoke (for example, through `VirtualMachine.dispose()`) the method invocation continues.

  Parameters:
    `thread` - the thread in which to invoke.
    `method` - the `Method` to invoke.
    `arguments` - the list of `Value` arguments bound to the invoked method. Values from the list are assigned to arguments in the order they appear in the method signature.
    `options` - the integer bit flag options.
  Returns:
    a `Value` mirror of the invoked method's return value.
  Throws:
    `IllegalArgumentException` - if the method is not a member of this object's class, if the size of the argument list does not match the number of declared arguemnts for the method, if the method is a constructor or static intializer, or if `INVOKE_NONVIRTUAL` is specified and the method is either abstract or an interface member.
    `{@link` - InvalidTypeException} if any argument in the argument list is not assignable to the corresponding method argument type.
    `ClassNotLoadedException` - if any argument type has not yet been loaded through the appropriate class loader.
    `IncompatibleThreadStateException` - if the specified thread has not been suspended by an event.
    `InvocationException` - if the method invocation resulted in an exception in the target VM.
    `InvalidTypeException` - If the arguments do not meet this requirement -- Object arguments must be assignment compatible with the argument type. This implies that the argument type must be loaded through the enclosing class's class loader. Primitive arguments must be either assignment compatible with the argument type or must be convertible to the argument type without loss of information. See JLS section 5.2 for more information on assignment compatibility.

### disableCollection

    public void disableCollection()

  Prevents garbage collection for this object. By default all `ObjectReference` values returned by JDI may be collected at any time the target VM is running. A call to this method guarantees that the object will not be collected. `enableCollection()` can be used to allow collection once again.

  Calls to this method are counted. Every call to this method requires a corresponding call to `enableCollection()` before garbage collection is re-enabled.

  Note that while the target VM is suspended, no garbage collection will occur because all threads are suspended. The typical examination of variables, fields, and arrays during the suspension is safe without explicitly disabling garbage collection.

  This method should be used sparingly, as it alters the pattern of garbage collection in the target VM and, consequently, may result in application behavior under the debugger that differs from its non-debugged behavior.

### enableCollection

    public void enableCollection()

  Permits garbage collection for this object. By default all `ObjectReference` values returned by JDI may be collected at any time the target VM is running. A call to this method is necessary only if garbage collection was previously disabled with `disableCollection()`.

### isCollected

    public boolean isCollected()

  Determines if this object has been garbage collected in the target VM.

  Returns:
    `true` if this `ObjectReference` has been collected; `false` otherwise.

### uniqueID

    public long uniqueID()

  Returns a unique identifier for this ObjectReference. It is guaranteed to be unique among all ObjectReferences from the same VM that have not yet been disposed. The guarantee applies as long as this ObjectReference has not yet been disposed.

  Returns:
    a long unique ID

### waitingThreads

    public List waitingThreads()
                        throws IncompatibleThreadStateException

  Returns a List containing a `ThreadReference` for each thread currently waiting for this object's monitor. See `ThreadReference.currentContendedMonitor()` for information about when a thread is considered to be waiting for a monitor.

  Not all target VMs support this operation. See VirtualMachine#canGetMonitorInfo to determine if the operation is supported.

  Returns:
    a List of `ThreadReference` objects. The list has zero length if no threads are waiting for the monitor.
  Throws:
    `UnsupportedOperationException` - if the target VM does not support this operation.
    `IncompatibleThreadStateException` - if any waiting thread is not suspended in the target VM

### owningThread

    public ThreadReference owningThread()
                                 throws IncompatibleThreadStateException

  Returns an `ThreadReference` for the thread, if any, which currently owns this object's monitor. See `ThreadReference.ownedMonitors()` for a definition of ownership.

  Not all target VMs support this operation. See VirtualMachine#canGetMonitorInfo to determine if the operation is supported.

  Returns:
    the `ThreadReference` which currently owns the monitor, or null if it is unowned.
  Throws:
    `UnsupportedOperationException` - if the target VM does not support this operation.
    `IncompatibleThreadStateException` - if the owning thread is not suspended in the target VM

### entryCount

    public int entryCount()
                   throws IncompatibleThreadStateException

  Returns the number times this object's monitor has been entered by the current owning thread. See `ThreadReference.ownedMonitors()` for a definition of ownership.

  Not all target VMs support this operation. See VirtualMachine#canGetMonitorInfo to determine if the operation is supported.

  Returns:
    the integer count of the number of entries.
  Throws:
    `UnsupportedOperationException` - if the target VM does not support this operation.
    `IncompatibleThreadStateException` - if the owning thread is not suspended in the target VM
  See Also:
    `owningThread()`

### equals

    public boolean equals(Object obj)

  Compares the specified Object with this ObjectReference for equality.

  Overrides:
    `equals` in class `Object`
  Returns:
    true if the Object is an ObjectReference, if the ObjectReferences belong to the same VM, and if applying the "==" operator on the mirrored objects in that VM evaluates to true.

### hashCode

    public int hashCode()

  Returns the hash code value for this ObjectReference.

  Overrides:
    `hashCode` in class `Object`
  Returns:
    the integer hash code

Overview | Package | Class | Use | Tree | Index | Help
| Java Debug Interface
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD